home *** CD-ROM | disk | FTP | other *** search
/ Shareware Super Platinum 8 / Shareware Super Platinum 8.iso / mac / PROGTOOL / FGIN101.ZIP;1 / FGINPUT.DOC < prev    next >
Encoding:
Text File  |  1993-06-12  |  8.2 KB  |  270 lines
  1. /****************************************************************************\
  2.                 Line Input  v1.01 (c) 1993  Douglas Peterson
  3.                        for use with Fastgraph (tm)
  4. \****************************************************************************/
  5.  
  6.  
  7.       This is a C library for getting data input in both text and graphics
  8.    modes.  It consists of only three functions:
  9.    input_line(), define_parameters(), and restore_default_colors().
  10.  
  11.       I apologize in advance for this documentation, hey i'm a programmer
  12.    right??
  13.  
  14.       Copy the include file FGINPUT.H wherever it is you like your include
  15.    files and the 2 .LIB files:  FGINLG.LIB and FGINSM.LIB whereever you
  16.    like your .LIB files.  FGINLG.LIB is for the large memory model and
  17.    FGINSM.LIB is for the small memory model.  Be sure to link one or the
  18.    other into your code as well as the appropriate Fastgraph (tm) library.
  19.  
  20.       This library is 'Freeware', that is you don't need to pay me for it.
  21.    Questions, suggestions, or problems can be addressed to me via the Dust
  22.    Devil BBS (702) 796-7134 or Software Creations BBS (508) 368-1714.  My
  23.    user name is 'Douglas Peterson'.
  24.  
  25.  
  26.  
  27. /****************************************************************************\
  28.  
  29.    Function Descriptions
  30.  
  31. \****************************************************************************/
  32.  
  33. ------------------------------
  34.  void define_parameters(void)
  35. ------------------------------
  36.  
  37. Description:
  38.  
  39.       This function MUST be called after a call to fg_setmode() and before
  40.    calling input_line() or restore_default_colors().  It sets up global
  41.    parameters that vary depending on the current video mode.  It also calls
  42.    restore_default_colors().  If your only using one video mode throughout
  43.    your program, you will only have to call this function once.
  44.  
  45. Parameters:
  46.  
  47.       None.
  48.  
  49. Returns:
  50.  
  51.       None.
  52.  
  53.  
  54. ----------------------------------------
  55.  int input_line(char *line, char *mask)
  56. ----------------------------------------
  57.  
  58. Description:
  59.  
  60.       This is the heart of it all.  A Single purpose, multi-mode input
  61.    routine.  Pass it a place to store the returned line and a mask and that's
  62.    all there is to it.  The (line) string contains the default value shown
  63.    to the user and the mask determines how many characters and even what
  64.    keys can be typed in each character cell.  In graphics mode, the left and
  65.    bottom corner of the input box are defined by the current graphics cursor
  66.    position, and in text modes the left column and row are defined by the
  67.    current text cursor position.
  68.  
  69. Parameters:
  70.  
  71.    char *line
  72.  
  73.       This is the buffer that will contain the characters typed by the
  74.    user.  It must be set to "" if you don't want a default value shown when
  75.    the input box appears.  For instance if you did:
  76.  
  77.       char name[11]="Douglas";
  78.  
  79.       input_line(name,"Aaaaaaaaaa");
  80.  
  81.       The user would see an input box ten characters long, and the word
  82.    "Douglas" would be displayed highlighted in the box.  If the first key
  83.    typed is a printable character (not and arrow key or CR or delete, etc)
  84.    the word "Douglas" disappears and they start editing a blank box.  On the
  85.    other hand if they had hit an arrow key, the word "Douglas" would be
  86.    un-highlighted and they would continue editing "Douglas".
  87.  
  88.       If instead you did:
  89.  
  90.       char name[11]="";
  91.  
  92.       input_line(name,"Aaaaaaaaaa");
  93.  
  94.       The user would see an input box ten characters long, but would be
  95.    blank.  You MUST not allocate a character array without initializing it
  96.    to something or you will get garbage on the screen.  There's no way for
  97.    the code to detect garbage from valid English words.
  98.  
  99.  
  100.    char *mask
  101.  
  102.       The (mask) string determines how many characters can be typed and
  103.    what keys can be hit in each cell.
  104.  
  105.       X       Allow any key, force to upper case
  106.       x  Allow any key
  107.       #       Allow only 0 thru 9 and +-,./
  108.       9       Allow only 0 thru 9
  109.       N       Allow a - z, A - Z, 0 - 9, +-,./ and force to upper case
  110.       n       Allow a - z, A - Z, 0 - 9, +-,./
  111.       A       Allow a - z, A - Z, and force to upper case
  112.       a       Allow a - z, A - Z
  113.       Y       Allow only y,Y,n,N and force to upper case
  114.  
  115.       Any invalid mask character will result in the user not being able to
  116.    type any key other than the space bar.  Extended keys are allowed, but
  117.    only the left and right arrow keys are considered so they're allowance
  118.    is transparent. Plus all editing keys are always allowed.
  119.  
  120.  
  121. Editing keys supported:
  122.  
  123.       Carrage return
  124.       Escape
  125.       Backspace
  126.       Delete
  127.       Insert
  128.       Left arrow
  129.       Right arrow
  130.       Home
  131.       End
  132.  
  133.  
  134. Returns:
  135.  
  136.       0       If the user pressed Carrage Return
  137.       -1 If the user pressed Escape ((line) is not altered)
  138.       1       If the (mask) length exceeds the buffer (95 characters)
  139.       2       If the current video mode is not supported
  140.       3       If define_parameters() has not been called
  141.  
  142.  
  143. -----------------------------------
  144.  void restore_default_colors(void)
  145. -----------------------------------
  146.  
  147. Description:
  148.  
  149.       This function restores the colors assigned different elements of the
  150.    input box by default.  This function is usefull if your program changes
  151.    a number of color elements and you want them restored without worrying
  152.    about which ones have been changed and which have not.
  153.  
  154.  
  155. Parameters:
  156.  
  157.       None.
  158.  
  159.  
  160. Returns:
  161.  
  162.       None.
  163.  
  164.  
  165. /****************************************************************************\
  166.  
  167.    Color And Mode Considerations
  168.  
  169. \****************************************************************************/
  170.  
  171.  
  172. --------
  173.  COLORS
  174. --------
  175.  
  176.    /* Black and White Text mode (7) */
  177.  
  178.    Backcolor          = 0
  179.    BackHighlightcolor = 1
  180.    TextNormalcolor    = 1
  181.    TextHighlightcolor = 1
  182.  
  183.  
  184.    /* 16 Color Text modes (0 thru 3) */
  185.  
  186.    Backcolor          = 8
  187.    BackHighlightcolor = 7
  188.    TextNormalcolor    = 7
  189.    TextHighlightcolor = 15
  190.  
  191.  
  192.    /* 2 Color Graphics modes (6, 17) */
  193.  
  194.    BorderRcolor       = 0;
  195.    BorderTcolor       = 0;
  196.    Backcolor          = 0;
  197.    BackHighlightcolor = 1;
  198.    TextNormalcolor    = 1;
  199.    TextHighlightcolor = 0;
  200.    Cursorcolor        = 1;
  201.  
  202.  
  203.    /* 4 Color Graphics modes  (4, 5) */
  204.  
  205.    BorderLcolor       = 1;
  206.    BorderBcolor       = 1;
  207.    BorderRcolor       = 1;
  208.    BorderTcolor       = 1;
  209.    Backcolor          = 0;
  210.    BackHighlightcolor = 1;
  211.    TextNormalcolor    = 3;
  212.    TextHighlightcolor = 3;
  213.    Cursorcolor        = 2;
  214.  
  215.  
  216.    /* 16+ Color Graphics modes (13, 14, 16 thru 29)*/
  217.  
  218.    BorderLcolor       = 0
  219.    BorderBcolor       = 0
  220.    BorderRcolor       = 15
  221.    BorderTcolor       = 15
  222.    Backcolor          = 8
  223.    BackHighlightcolor = 7
  224.    TextNormalcolor    = 7
  225.    TextHighlightcolor = 15
  226.    Cursorcolor        = 4
  227.  
  228.  
  229. Descriptions:
  230.  
  231.       BorderTcolor                    Top side 1 pixel border in graphics modes
  232.       BorderLcolor                    Left side 1 pixel border in graphics modes
  233.       BorderRcolor                    Right side 1 pixel border in graphics modes
  234.       BorderBcolor                    Bottom side 1 pixel border in graphics modes
  235.       Backcolor                               Normal background color in any mode
  236.       BackHighlightcolor   Highlighted background color any mode
  237.       TextNormalcolor         Normal color of text in any mode
  238.       TextHighlightcolor      Highlighted text color in any mode
  239.       Cursorcolor                             Color of the cursor in graphics modes
  240.  
  241.  
  242. -------
  243.  MODES
  244. -------
  245.  
  246. Considerations:
  247.  
  248.    Modes 0 thru 7, 13, and 14 can only use TextSize of 8
  249.  
  250.    Mode  16 can only use TextSize of 14 and 16.  TextSize is set to 14
  251.             after call to default_parameters().
  252.  
  253. ----------
  254.  TextSize
  255. ----------
  256.  
  257.       This variable is 8 by default (14 for mode 16), but can be changed
  258.    to 14 or 16 to increase the size of the font.  For larger video modes
  259.    you almost have to increase the size in order to see the characters
  260.    clearly.
  261.  
  262.       TextSize=8;
  263.       TextSize=14;
  264.       TextSize=16;
  265.  
  266.       Are all valid.  Remember to change this BEFORE calling input_line().
  267.    Any value other than 8,14, or 16 will be changed to 8 (14 for mode 16).
  268.  
  269.  
  270.